[DEBT] CLAUDE.md out of date: Stage 3 opened in May; "external integrations" non-goal never amended

Em uma frase: o arquivo que orienta toda sessão de agente no repo diz
que o Stage 3 é "próximo" e que "integrações externas foram removidas" —
mas o Stage 3 abriu em maio de 2026 com a integração Datadog, de forma
deliberada e documentada; um agente que siga o CLAUDE.md à letra pode
recusar ou desfazer trabalho legítimo.

Aberta como PR direta, não como issue: é correção factual de doc mais um
ADR que registra decisão já tomada — a revisão do dono acontece na própria
PR. Referências arquivo:linha apontam para main @ da16235. Esta mudança
é independente: toca só documentação. Toda preocupação da análise
adversária tem disposição final.

Qual é a dívida?

Duas afirmações em CLAUDE.md estão factualmente desatualizadas:

1. Tabela de stages (CLAUDE.md:33-34):

| 2 | Intelligence Platform (MVP) | **Current** — … |
| 3 | Scale & Enterprise Readiness | Next — SSO, fine-grained RBAC, cross-system correlation (CI, incidents), anonymized benchmarking |

2. Não-objetivo (CLAUDE.md:70):

- billing, webhooks, or external integrations (the original SaaS scaffold had these; they were intentionally removed)

Enquanto isso, o repositório contém uma integração externa completa:
platform/lib/integrations/datadog/{client,sync}.ts,
platform/src/app/api/integrations/datadog/events/route.ts,
platform/src/app/api/cron/sync-integrations/route.ts,
iris/analysis/dora_real.py, docs/integrations/datadog.md,
docs/PLAN-datadog.md, e a seção "DORA (real) — Datadog-derived" em
docs/METRICS.md.

E docs/DECISIONS.md não tem entrada sobre a abertura do Stage 3 — a
entrada de 2026-04-12 diz literalmente que os itens de Stage 3 "remain
explicit non-goals until Stage 3 is formally opened" (:225), e a
formalização nunca aconteceu.

Por que é dívida?

• CLAUDE.md é o arquivo de contexto carregado em toda sessão de Claude
  Code. Um não-objetivo desatualizado é uma instrução ativa para recusar
  Stage 3.
• É o único dos três arquivos de contexto com essa inconsistência:
  AGENTS.md e WINDSURF.md não repetem a tabela nem o não-objetivo
  (verificado por grep). Nenhum .cursorrules, GEMINI.md ou
  .github/copilot-instructions.md existe na raiz.
• O custo é de trabalho mal direcionado, não de código: um agente ou
  contribuidor novo pode (a) recusar uma tarefa de integração citando o
  não-objetivo, (b) propor "remover a integração Datadog para voltar ao
  escopo", ou (c) rotular como Stage 3 algo que já é prática corrente.
• A inconsistência induz conclusões erradas em cascata: uma leitura do repo
  guiada pelo CLAUDE.md classifica o Datadog como "drift não declarado";
  a evidência abaixo mostra que foi sancionado.

Como chegou aqui?

O Stage 3 abriu explicitamente, mas fora do CLAUDE.md e do
DECISIONS.md:

• CHANGELOG.md v1.0.6 (2026-05-13): "Stage 3 opens: Iris can now consume
  a customer's DORA event stream from Datadog and report real Change Failure
  Rate, MTTR, deploy frequency…"
• docs/PLAN-datadog.md (ligado à issue [FEAT] Integração Datadog — área de Integrations nos settings da org #15): "This is also the implicit
  opening of Stage 3 ('Scale & Enterprise Readiness') since cross-system
  correlation is explicitly listed there in the project CLAUDE.md. We're not
  adopting any other Stage 3 abstractions (RBAC matrix, SCIM, policy engine)
  here — only the integration capability."

Ou seja: a decisão foi tomada e registrada em CHANGELOG + PLAN + issue, mas
a tabela de stages, a linha do não-objetivo e o registro de decisões nunca
foram emendados. O parêntese do não-objetivo ("the original SaaS scaffold
had these") sugere que a linha sempre visou billing/webhooks, não fontes de
dados analíticos — a redação é que ficou ampla demais.

Plano de migração

• Tabela de stages — Stage 2: manter Current, acrescentar "refinement
  ongoing". Stage 3: "Opened 2026-05 with cross-system correlation
  (Datadog DORA events — CHANGELOG v1.0.6, docs/PLAN-datadog.md, ADR
  2026-05-13 in docs/DECISIONS.md). Still pending: SSO, fine-grained
  RBAC, anonymized benchmarking."
• Não-objetivo — separar o que foi removido do que é escopo: "billing and
  webhooks (the original SaaS scaffold had these; they were intentionally
  removed). Analytical data-source integrations (e.g. Datadog DORA events)
  are Stage 3 scope; the Datadog integration ([FEAT] Integração Datadog — área de Integrations nos settings da org #15, docs/PLAN-datadog.md)
  is the precedent for how one lands — issue and plan first, then code."
• CLAUDE.md:36 → "Work that lands should fit Stage 2 refinement or
  Stage 3's opened integration capability — …". :40 ("Focus Areas
  (Stage 2)") mantido: Stage 2 continua Current; definir foco de
  Stage 3 é política de produto, fora desta mudança (ataque 1).
• ADR em docs/DECISIONS.md — "2026-05-13 — Stage 3 Opens With
  Integration Capability Only", no formato do arquivo (Decision / Context
  / Rationale / Consequences), marcado como registrado retroativamente
  em 2026-09-08. Registra a decisão já tomada e shipada; não toma
  decisão nova. Inserido em ordem cronológica, antes da entrada de
  2026-06-11.

Critérios de aceite (antes do merge)

• Revisão do texto do ADR pelo dono do projeto — é o único artefato
  desta issue que fala em nome do projeto (a redação do CLAUDE.md é
  correção factual).

Deadline / gatilho pra pagar

Antes da próxima sessão de agente que toque em integrações ou Stage 3.
Custo estimado: quinze minutos incluindo a revisão do ADR. Não há gatilho de
release — é doc.

Evidência de validação (isolada: main + só esta mudança)

• CLAUDE.md e docs/DECISIONS.md não são lidos por nenhum script:
  grep -rn "CLAUDE.md" scripts/ iris/ .github/workflows/ retorna só
  iris/analysis/priming_detector.py:47, que verifica existência do
  arquivo (sinal de "priming"), não conteúdo. Risco de código: zero.
• Suíte completa: 473 pass / 0 fail (LC_ALL=C; inalterada — nenhum
  teste adicionado, nenhum código tocado).
• A/B end-to-end (engine base vs engine com esta mudança, mesmo
  repo-alvo, runs em par): metrics.json e report.md byte-idênticos.
  (Se o repo analisado for o próprio Iris após o merge,
  priming.files[CLAUDE.md].size_bytes muda — efeito do arquivo analisado
  ter crescido, não do código.)

Como reproduzir

grep -rn "CLAUDE.md" scripts/ iris/ .github/workflows/   # só priming_detector.py:47
LC_ALL=C pytest tests/ -q                                  # 473 passed

Análise adversária (pós-implementação) — toda linha com disposição final

Fora do escopo

• Qualquer mudança de código.
• Reabrir a decisão de integrar Datadog (já tomada em [FEAT] Integração Datadog — área de Integrations nos settings da org #15).
• Reescrever docs/VISION.md / docs/PRINCIPLES.md.
• Definir a lista de focos do Stage 3.

Issues relacionadas (verificado contra as 63 issues do repo, abertas e fechadas — sem duplicata)

• [FEAT] Integração Datadog — área de Integrations nos settings da org #15 (fechada) — Integração Datadog. É a origem da abertura do Stage 3: seu corpo diz "Stage: 3 … 'cross-system correlation (CI, incidents)' é exatamente um dos itens listados no roadmap de Stage 3 no CLAUDE.md". Nenhuma issue, aberta ou fechada, rastreia a atualização do CLAUDE.md que [FEAT] Integração Datadog — área de Integrations nos settings da org #15 implicou — é essa a lacuna.
• [FEAT] ADR + reabrir Princípio #7 — exceção para telemetria de vendor sob privacy-by-construction #66 (fechada) — ADR + reabrir Princípio build(deps-dev): Bump @types/bcryptjs from 2.4.6 to 3.0.0 in /platform #7. Precedente de ADR proposto via issue e registrado em docs/DECISIONS.md; esta issue segue o mesmo caminho.
• [DEBT] Auditar o projeto inteiro contra a regra 6 do CLAUDE.md (open source / agnóstico de organização) #179 (fechada) — Auditar o projeto contra a regra 6 do CLAUDE.md. Outra auditoria do CLAUDE.md, sobre tema distinto (org-agnostic); não se sobrepõe.
• Pré-requisitos de engine para a coleta centralizada #208–[FEAT] Ativar o schedule e acompanhar as métricas de sucesso #229 (abertas, épico de coleta centralizada) — várias se declaram "Stage 2 — Ingestion: reliability", citando as Focus Areas do CLAUDE.md. A correção da tabela de stages não muda a classificação delas.

Referências

• CLAUDE.md:27-36 (stages), :40-45 (focus), :60-72 (non-goals) — main @ da16235.
• docs/DECISIONS.md:225 ("until Stage 3 is formally opened"), :229-275 (entradas de 2026-04-12, formato de referência), :277 (entrada de 2026-06-11, ponto de inserção).
• CHANGELOG.md — entradas v1.0.6 "Datadog DORA integration" (2026-05-13) e v1.0.7 "Datadog integration: post-launch fixes".
• docs/PLAN-datadog.md (cabeçalho e §1); issue [FEAT] Integração Datadog — área de Integrations nos settings da org #15.
• iris/analysis/priming_detector.py:3,10,47 (único consumidor de CLAUDE.md).